/*=============================================================================*
 *  Copyright 2004 The Apache Software Foundation
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *=============================================================================*/
package topics;

import topics.expression.TopicExpression;
import topics.expression.TopicExpressionException;

/**
 * The set of topics that a particular NotificationProducer supports.
 */
public interface TopicSpaceSet
{
   /**
    * Sets the boolean that indicates if this topic set is fixed as defined by
    * the WS-BaseNotification specification.
    *
    * @param fixed
    */
   void setFixed( boolean fixed );

   /**
    * Returns a boolean that indicates if this topic set is fixed as defined by
    * the WS-BaseNotification specification.
    */
   boolean isFixed(  );

   /**
    * Returns a TopicSpace for a given namespace uri.
    *
    * @param namespaceURI
    * @return the TopicSpace for the given uri, or null if there is no TopicSpace found.
    */
   TopicSpace getTopicSpace( String namespaceURI );

   /**
    * Resturns the TopicSpaces maintained by this TopicSpaceSet
    *
    * @return An array of TopicSpace objects.
    */
   TopicSpace[] getTopicSpaces(  );

   /**
    * Adds the TopicSpace to the TopicSpaceSet.
    *
    * Note. If the TopiSpace already exists, this method will add all the known Topics
    * to the passed-in TopicSpace and set it as the current TopicSpace in the TopicSpaceSet.
    * This will ensure there is only 1 TopicSpace in the set and it is complete...
    *
    * @param topicSpace
    */
   TopicSpace addTopicSpace( TopicSpace topicSpace );

   /**
    * Evaluates a {@link TopicExpression} against the TopicSpaceSet and returns an array of matching Topics.
    *
    * @param topicExpr The topicexpression (query) to be used to search againt the TopicSpaceSet.
    * @return An array of Topics which were found based on the topicexpression
    * @throws TopicExpressionException
    */
   Topic[] evaluateTopicExpression( TopicExpression topicExpr )
   throws TopicExpressionException;

   /**
    * Removes a TopicSpace from the TopicSpaceSet for a given namespace uri.
    *
    * @param namespaceURI
    */
   void removeTopicSpace( String namespaceURI );
}